Skip to main content

Credit Card Internet Payment Guide using Payment Vault - For Online Payment Websites

Introduction​

In this guide we will be walking you through how to create single payment initiated by an end user through the internet using the Payment Vault web service. Our objective will be to establish the basics by using specific credit card payment type examples, however the examples should provide you with the information needed to customize to your specific needs. Internet Payments are initiated and authorized via the internet by the end-user. Credit card payments are those payments against card brands such as Visa or Mastercard accounts. If you have a customer facing online platform where users can login and initiate payments from their credit cards, you will want to follow this guide for proper payment routing.

Getting Started​

Here's what you'll do in this guide

  • Create a single credit card payment with custom data.
    note

    Please review the Credential on File Guide if you are setup on the EPS Card Gateway or the Bridgepay/T-Gate network with First Data North. There are special rules from the card brands you will need to account for when storing card accounts that are discussed outside of this guide.

Prerequisites needed before continuing

  • You will want to obtain your test credentials in order to try any of the examples in this guide. You should have received these from your Implementation Coordinator.
  • Review the Authentication guide for an understanding on how to authenticate to the EPS web service. This guide will walk you through sending a test connection and test credentials to ensure you are able to authenticate before moving forward.
  • Review the Vaulting Customer and Account Data guide on how to create customers and accounts used in this guide.
  • Download the Payment Vault WSDL file from the Downloads menu

Create a single credit card payment with custom data workflow guide​

For this guide we will walk through a hypothetical example where a customer is making a one-time payment of 25 dollars for purchasing a product that they have initiated through a customer facing website. We have given the product an ID of A1234 which we will track with the transaction. The customer will be a returning user which is authenticated in the payment site and their payment information has been previously vaulted with tokens called referenceIDs.

  • Step 1 Step 1 The first thing that will need to occur is to capture the required information needed to build the web request. Since this is Payment Vault we will be dealing with previously vaulted customers and accounts and will know what the reference ids are. For this example, we will say the customer has initiated a payment on our website and we have gathered the following information.
    • Account reference id: 111222333444567
    • Amount: 25.00 purchase amount.
    • Product ID: A1234 from product selection
    • CCVS: 3123
  • Step 2 Using the collected information, we will populate a SaleFromCardAccount request in order to process this payment.
    • Add the accountReferenceId. This is a token that represents the account information that was previously stored in the EPS system. This will be what the EPS system will use to pull the credit card account for the actual payment.
    • We will also add the productid they purchased to Field1 so it will be stored with the transaction and can be reported on in Transaction Reporting.
    • Since this is an internet payment, we need to specify “Internet” as the “PaymentOrigin”.

Here is what our completed SaleFromCardAccount request will look like for this example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
   <soapenv:Header>
      <pv:SecurityHeader>
         <pv:BinarySecurityToken>your security token here</pv:BinarySecurityToken>
      </pv:SecurityHeader>
   </soapenv:Header>
   <soapenv:Body>
    <pv:SaleFromCardAccount>
        <pv:storeId>0</pv:storeId>
        <pv:storeKey isNull="true" />
        <pv:entityId>entityId of your merchant</pv:entityId>
        <pv:locationId>locationId of the transaction</pv:locationId>
        <pv:accountReferenceId>111222333444567</pv:accountReferenceId>
        <pv:paymentOrigin>Internet</pv:paymentOrigin>
        <pv:Amount>25.00</pv:Amount>
        <pv:terminalNumber>__WebService</pv:terminalNumber>
        <pv:TransactionNumber>112</pv:TransactionNumber>
        <pv:Description> </pv:Description>
        <pv:Field1>A1234</pv:Field1>
        <pv:Field2></pv:Field2>
        <pv:Field3></pv:Field3>
        <pv:CCVS>3123</pv:CCVS>
        <pv:clientIP></pv:clientIP>
        <pv:storedCredential>Customer</pv:storedCredential>
    </pv:SaleFromCardAccount>
	</soapenv:Body>
</soapenv:Envelope>
  • Step 3 Once this request is sent to the endpoint, we should get a successful response and there are a few key items that are important to log with this response.
    • ReferenceNumber - EPS generates this value for you to use for pulling reporting information on the transaction later. You will want to store this number with the transaction in your database.
    • Success - indicates a successful transaction.
    • Error - indicates if an error has occurred.
    • ResponseCode - EPS code signifying result of the request.
    • ActualDate - when the transaction was created in EPS.
    • ResponseMessage - detailed description for the response code when applicable.

Here is what our successful response looks like for this example.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <SaleFromCardAccountResponse xmlns="https://ssl.selectpayment.com/PV">
            <SaleFromCardAccountResult>
                <ReferenceNumber>T:82Q1Y1A7A2L</ReferenceNumber>
                <Success>true</Success>
                <Error>false</Error>
                <ResponseCode>Success</ResponseCode>
                <ActualDate>2010-12-30T00:00:00.0000000-06:00</ActualDate>
                <ResponseMessage>Success</ResponseMessage>
                <OriginatedAs>Card_Transfer</OriginatedAs>
            </SaleFromCardAccountResult>
        </SaleFromCardAccountResponse>
    </soap:Body>
</soap:Envelope>

Handling Errors and Failed Requests​

Not all requests will be successful, so we will need to run through a few common errors you should be ready to handle.

  • Duplicate transaction - Duplicate transactions will be declined. Transactions are checked against our duplicate table which is a rolling 75 days of history and is checked against other transactions for the same merchant (entityID). It is important that transactions that receive a duplicate error are not automatically retried and there are two ways to handle it.
    • The transaction is a true duplicate and will not need another attempt. Record the response and no further action is needed.
    • You are certain that the transaction is not really a duplicate and need it to process. For WEB payments a duplicate is flagged when the Transaction Number is not unique. This means the Transaction Number value will need to change to something unique and resubmit the request.
  • Timeout waiting for response - Systems should be designed to wait for 10 seconds for Card transactions to receive a response before timing out. If a timeout occurs, you can attempt to query the system with one of the GetTransaction methods to verify if the transaction was received. If it was not the transaction can be resubmitted.

Next Steps​

  • Customize the workflows to fit your specific business needs.
    • You can apply the principles shown in these examples and customize the requests using the API Reference to suit your needs
  • Review the API Reference
    • This guide is just a starting point to show a common use case scenario for making internet payments. Please review the API Reference to see all APIs and their technical specifications.
  • Explore other guides
    • We have other guides to show how to leverage our APIs in other common use cases so if this one doesn't cover what you are looking for, give another guide a try.
  • Get certified and move into production
    • Ready to put your new code into production use? Refer to this process guide that explains our certification steps and how to contact us to get started.